/*
 * Copyright (c) 2009. Silenus Consultoria, S.L.
 */
package es.silenus.detecta.service;

import es.silenus.detecta.dao.Page;

import es.silenus.detecta.model.User;

import org.springframework.dao.DataAccessException;

import org.springframework.security.userdetails.UserDetailsManager;
import org.springframework.security.userdetails.UsernameNotFoundException;

import java.util.Map;


/**
 * User service interface.
 *
 * @author <a href="mailto:malonso@silenus-consultoria.es">Mariano Alonso</a>
 * @since 24-jun-2009 12:21:34
 */
public interface UserService extends UserDetailsManager {
	/**
	 * Locates a user by its internal identifier.
	 *
	 * @param id the internal identifier.
	 *
	 * @return the user.
	 */
	public User findUserById(final Integer id);

	/**
	 * Modify the current user's password. This should change the user's password in the persistent user repository
	 * (datbase, LDAP etc) and should also modify the current security context to contain the new password.
	 *
	 * @param userName the user name.
	 * @param oldPassword current password (for re-authentication if required)
	 * @param newPassword the password to change to
	 */
	public void changePassword(final String userName, String oldPassword, String newPassword);

	/**
	 * Finds the objects that satisfy a search criteria expressed as an example object bean and a pagination object
	 * to limit and sort.
	 *
	 * @param sample the sample criteria.
	 * @param start the start index.
	 * @param limit the limit index.
	 * @param sortFields the sort fields.
	 * @param sortDirections the sort directions.
	 *
	 * @return the page.
	 */
	public Page<User> findByExample(
		final Map<String, Object> sample, int start, int limit, final String[] sortFields, final String[] sortDirections);

	/**
	 * Locates the user based on the username. In the actual implementation, the search may possibly be case
	 * insensitive, or case insensitive depending on how the implementaion instance is configured. In this case, the
	 * <code>UserDetails</code> object that comes back may have a username that is of a different case than what was
	 * actually requested..
	 *
	 * @param username the username presented to the {@link
	 * 				org.springframework.security.providers.dao.DaoAuthenticationProvider}
	 *
	 * @return a fully populated user record (never <code>null</code>)
	 *
	 * @throws UsernameNotFoundException if the user could not be found or the user has no GrantedAuthority
	 * @throws DataAccessException if user could not be found for a repository-specific reason
	 */
	public User loadUserByUsername(String username) throws UsernameNotFoundException, DataAccessException;
}
